Creating and Manipulating Transform Objects (IM: XO)

Inside Macintosh: QuickDraw GX Objects /: Chapter 6 - Transform Objects / Using Transform Objects

Creating and Manipulating Transform Objects
This section describes how you can create and interact with transform objects as whole entities--to create, dispose of, copy, compare, and clone them. Manipulating the individual properties of transform objects is described under "Copying, Comparing, and Cloning Transform Objects" beginning on page 6-16 and in subsequent sections.

Creating and Disposing of Transform Objects
QuickDraw GX provides the GXNewTransform function to allow you to create a new transform object. You can also create a new transform object by copying an existing one with the GXCopyToTransform function. Once you have created a transform object, you can modify its properties using functions such as those described in the section "Copying, Comparing, and Cloning Transform Objects" beginning on page 6-16.
You need to explicitly create a transform object if you want a single nondefault transform to apply to several shapes. You can also indirectly cause the creation of a new transform object by modifying a transform property under certain conditions; see "Implicit Creation of Transform Objects" on page 6-18 for more information.
To delete your application's reference to a transform object, call the GXDisposeTransform function, which may or may not actually release the memory allocated for that transform object, depending on the transform's owner count. The function decreases the transform object's owner count by 1; if that brings the owner count to zero, the transform is completely deleted and its memory released. For more discussion of transform-object owner counts, see "Manipulating a Transform Object's Owner Count" on page 6-19.
Listing 6-1 is a code fragment that creates a transform object (myTransform) and assigns it to a shape object (myRectangle).
Listing 6-1 Creating and disposing of a transform object
gxTransform    myTransform;
gxShape        myRectangle;
myTransform =  GXNewTransform();
.
.  /* set the transform object's properties (not shown) */
.
myRectangle =  GXNewRectangle(gxRectangleType);
GXSetShapeTransform(myRectangle, myTransform);
GXDisposeTransform(myTransform);
Notice that the code disposes of the myTransform reference to the transform object immediately after it is assigned to the shape. The code no longer needs the reference, and this decreases the transform's owner count, allowing it to be deleted as soon as the shape no longer needs it. The proper place to call GXDisposeTransform is immediately after you have finished using a transform in your code, even if you know that another object's use prevents the transform from being deleted at that time.
The GXNewTransform function is described on page 6-33. The GXDisposeTransform function is described on page 6-34.

Copying, Comparing, and Cloning Transform Objects
You can use the GXCopyToTransform function to copy information from one transform object to another or to create a new copy of a transform object.
You can test if two transform-object references refer to the same transform object by simply testing the references for equality. You can also compare two different transform objects for equality with the GXEqualTransform function. For two transform objects to be equal, their clips, mappings, view port lists, and hit-test parameters must have identical values, although their owner count and tag list do not need to be identical. Transform object copies created with the GXCopyToTransform function are always equal, by these criteria, to the transform from which they were copied.
The following code fragment creates a copy (lineTransform) of the transform object associated with the default line shape. It then scales the line shape by changing
its transform mapping. Finally, it recopies the original transform back into lineTransform to restore the unscaled values.
gxTransform    lineTransform, savedTransform;
gxShape        defaultLine;
defaultLine = GXGetDefaultShape(gxLineType);
lineTransform = GXGetShapeTransform(defaultLine);
savedTransform = GXCopyToTransform(nil, lineTransform);
GXScaleTransform(lineTransform, ff(2), ff(2), 0, 0);
.
.  /* use the scaled transform (not shown) */
.
GXCopyToTransform(lineTransform,savedTransform);
GXDisposeTransform(savedTransform);
Note that the first call to GXCopyToTransform in the above code creates a new transform object, whereas the second call causes the contents of one transform to be copied into another.
In certain circumstances, you may want to copy a reference to a transform object without actually copying the object itself. For example, you may want two variables to refer to the same transform object, so that editing one of them affects both. Or, you may want to preserve a reference to a transform so that it cannot be inadvertently deleted. This is called cloning a transform; you can use the GXCloneTransform function to clone a transform object.
Functionally, GXCloneTransform does nothing more than increase the owner count of a transform. The code in Listing 6-2 clones a shape's original transform object to preserve it from being deleted, changes the shape's transform object temporarily to perform several operations (not shown in the example), and then restores the original transform. In this example, the original transform object is called saved and the one that is used for the operations is called newXform.
Listing 6-2 Cloning a transform to prevent it from being deleted
gxTransform saved = GXGetShapeTransform(aShape);
GXCloneTransform(saved);
GXSetShapeTransform(aShape, newXform);
.
.  /* use the new transform (not shown) */
.
GXSetShapeTransform(aShape, saved);
The saved transform object must be cloned because, in the process of associating a new transform object with a shape, the GXSetShapeTransform function decrements the owner count of the previously associated transform object. Cloning prevents the saved object from being deleted because cloning increments the owner count, which prevents the owner count of the saved transform object from going down to 0.
For more information about cloning objects, see the chapter "Introduction to Objects" in this book. For more information on manipulating transform owner counts, see the section "Manipulating a Transform Object's Owner Count" beginning on page 6-19 of this chapter.
The GXCopyToTransform function is described on page 6-35. The GXCloneTransform function is described on page 6-37. The GXEqualTransform function is described on page 6-36.
The GXScaleTransform function is described on page 6-60. The GXSetShapeTransform function is described in the chapter "Shape Objects" in this book.

Implicit Creation of Transform Objects
QuickDraw GX provides two kinds of functions that modify transform properties:

The first kind, such as GXSetTransformClip and GXSetTransformMapping, takes a transform reference as a parameter; it directly alters a property of the transform and thus affects all shapes that use that transform. No new transform object is created when you call this kind of function.
The second kind, such as GXSetShapeClip and GXSetShapeMapping, takes a shape reference as a parameter; it alters a property of whatever transform object is used by that shape. To keep from inadvertently affecting other shapes that use the same transform, QuickDraw GX creates a copy of the transform object and modifies the copy if more than one shape object shares the transform.

In addition, if you call a function that normally affects only a shape's geometry, such as GXRotateShape, and the shape's gxMapTransformShape attribute is also set, the shape's transform mapping is changed instead; in that case, if the transform is shared by more than one object, QuickDraw GX creates a copy and modifies the copy.
The gxMapTransformShape attribute is described in the chapter "Shape Objects" in this book. How it affects the functions described in this chapter is discussed in the section "Moving, Scaling, Rotating, and Skewing Shapes" beginning on page 6-23.

Loading and Unloading Transform Objects
Although you rarely need to, you can influence memory-allocation decisions involving objects that you have created. If your application needs to have a transform object in memory, you can force QuickDraw GX to load it into memory. When your application no longer needs the transform object in a loaded state, you can instruct QuickDraw GX to unload it.
You call the GXLoadTransform function to make sure that a transform object is in memory; if necessary, QuickDraw GX brings the object into memory from an unloaded state. You can call the GXUnloadTransform function to instruct QuickDraw GX that it is free to unload the transform object at any time. These functions are described in the memory management chapter of Inside Macintosh: QuickDraw GX Environment and Utilities.